home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / clipper / nfsrc21.zip / ACH2TB.PRG < prev    next >
Text File  |  1992-10-17  |  35KB  |  847 lines
  1. /*
  2.  * File......: ACH2TB.PRG
  3.  * Author....: Steve Kolterman
  4.  * CIS ID....: 76320,37
  5.  * Date......: $Date:   17 Oct 1992 16:26:12  $
  6.  * Revision..: $Revision:   1.4  $
  7.  * Log file..: $Logfile:   C:/nanfor/src/ach2tb.prv  $
  8.  * 
  9.  * This is an original work by Steve Kolterman and is placed in the
  10.  * public domain.
  11.  *
  12.  * Modification history:
  13.  * ---------------------
  14.  *
  15.  * $Log:   C:/nanfor/src/ach2tb.prv  $
  16.  * 
  17.  *    Rev 1.4   17 Oct 1992 16:26:12   GLENN
  18.  * Leo cleaned up the documentation block.
  19.  * 
  20.  *    Rev 1.3   07 Oct 1992 23:31:10   GLENN
  21.  * Latest Kolterman updates.
  22.  * 
  23.  *    Rev 1.2   15 Aug 1991 23:17:48   GLENN
  24.  * Last minute fix sent in by Steve Kolterman
  25.  * 
  26.  *    Rev 1.1   15 Aug 1991 23:06:16   GLENN
  27.  * Forest Belt proofread/edited/cleaned up doc
  28.  * 
  29.  *    Rev 1.0   14 Jun 1991 04:14:14   GLENN
  30.  * Initial revision.
  31.  *
  32.  */
  33.  
  34. /*  $DOC$
  35.  *  $FUNCNAME$
  36.  *     FT_Ach2tb()
  37.  *  $CATEGORY$
  38.  *     Menus/Prompts
  39.  *  $ONELINER$
  40.  *     Replace ACHOICE() with a Tbrowse object & multiple features.
  41.  *  $SYNTAX$
  42.  *     FT_Ach2tb( <nToprow>,<nTopcol>[,<nBotrow>][,<nBotcol>],<aArrey>,     ;
  43.  *           [<cBoxtype>],[<cBoxcolor>],[<cBoxtitle>],[<nTitlePos>],        ;
  44.  *           [<cUselcolor>],[<cTitlecolor>],[<cBarcolor>],[<cHkcolor>],     ;
  45.  *           [<lShadow>],[<lExecute>],[<nMsgrow>],[<nMsgcol>],              ;
  46.  *           [<cMsg.color>],[cElevbar],[cEbarcolor],[<cEbarside>],          ;
  47.  *           [<cNoSelcolor>],[<cTagch>],[<nStartelem>],[<lRscreen>],        ;
  48.  *           [<nTimeout>],[<nTimeoutval>],[<cUserfunc>] )
  49.  *      --> nOption
  50.  *
  51.  *  $ARGUMENTS$
  52.  *
  53.  *  <nToprow>   is the top row of the box to be drawn.  Required.
  54.  *
  55.  *  <nTopcol>   is the top column of the box to be drawn.  Required.
  56.  *
  57.  *  <nBotrow>   is the bottom row of the box to be drawn.  The default is
  58.  *     <nToprow>+Len(<aArrey>)+1 or maxrow()-2, whichever is less.
  59.  *
  60.  *  <nBotcol>   is the bottom column of the box to be drawn.  The default
  61.  *     is <nTopcol>+width of the widest element in <aArrey> +2.
  62.  *
  63.  *     It's been pointed out that the number of commas required to default
  64.  *     the <nBotrow> and <nBotcol> params. is at least slightly confusing.
  65.  *     So, some documentation on the requirements:
  66.  *     Default both:                           7,9,,   ARRAY:
  67.  *     Default <nBotrow>, specify <nBotcol>:   7,9,,20 ARRAY:
  68.  *     Default <nBotcol>, specify <nBotrow>:   7,9,15, ARRAY:
  69.  *
  70.  *  <aArrey>    is the arrey of options to present to the user.  Each
  71.  *     element can hold as many as five subelements, or as few as one.
  72.  *     Required.  Additional documentation below.
  73.  *
  74.  *  <cnBoxtype> is the type of box to draw.  Uses DispBox().  The
  75.  *     default is a double-line box.
  76.  *
  77.  *  <cBoxcolor> is the color with which to draw the box.  The default is
  78.  *     Setcolor().
  79.  *
  80.  *  <cBoxtitle> is title of the box drawn on <nToprow>.  The default is
  81.  *     no title.
  82.  *
  83.  *  <nTitlepos>  is the starting column position (to the right of
  84.  *     <nTopcol>) at which to draw <cBoxtitle>.  The default is 1.
  85.  *
  86.  *  <cUselcolor> is the color with which to draw unselected options.
  87.  *     The default is Setcolor().
  88.  *
  89.  *  <cTitlecolor> is the color with which to draw the box title.  The
  90.  *     default is yellow on red.
  91.  *
  92.  *  <cBarcolor>  is the color with which to draw the selection bar.
  93.  *     The default is yellow on black.
  94.  *
  95.  *  <cHkcolor>  is the default color with which to draw the hotkeys for
  96.  *     for each option.  This is used when no hotkey color is supplied
  97.  *     in <aArrey>.  The default is hiwhite on the current background
  98.  *     color.
  99.  *
  100.  *  <cShadow>   is a character string, either "L" or "R" (for left or
  101.  *     right) to designate the side of the box where a shadow will appear.
  102.  *     Leave this NIL to avoid drawing a shadow.  You might also leave
  103.  *     this NIL if you choose to use a .C or .ASM shadow function, which
  104.  *     is a good idea.  Shadoww(), included below, is flat-out SLOW.
  105.  *
  106.  *  <lExecute>  turn on/off execution of option when first letter is
  107.  *     pressed.  Rule:  setting in element 5 of each <aArrey> subarray
  108.  *     overrides <lexecute>.  If that element is left NIL, the <lexecute>
  109.  *     setting is used.  If <lexecute> is not passed and element 5 is NIL,
  110.  *     auto execution is turned ON.
  111.  *
  112.  *  <nMsgrow>  is the row on which to draw a message for each option.
  113.  *     The default is two rows below the bottom of the box.
  114.  *
  115.  *  <nMsgcol>  is the column at which to draw a message for each option.
  116.  *     The default is <nTopcol> +2.  To CENTER the message, pass "C".
  117.  *
  118.  *  <cMsgcolor>  is the default color with which to draw messages.  This
  119.  *     color is used when element 4 of each <aArrey> subarray is left NIL.
  120.  *     The default is Setcolor().
  121.  *
  122.  *  <cElevbar>  is the ASCII character to use as the elevator bar drawn
  123.  *     on the box.  Leave this NIL to draw no elevator bar.
  124.  *
  125.  *  <cEbarcolor>  is the color with which to draw the elevator bar.
  126.  *     This is ignored if <cElevbar> is NIL.
  127.  *
  128.  *  <cEbarside>  is a character string, either "L" or "R" (for left or
  129.  *     right) to designate the side of the box on which to draw the
  130.  *     elevator bar.  This is ignored if <cElevbar> is NIL.
  131.  *
  132.  *  <cNoselcolor>  is the color with which to draw unselectable options.
  133.  *     The default is white on black.
  134.  *
  135.  *  <cTagchar> is the ASCII character to use to draw tags that would
  136.  *     appear to the right of each option.  The default is *DIS*abled
  137.  *     tagging.  The default tag is "√" (chr(251)).
  138.  *
  139.  *  <nStartelem>  is the number of the option where the selection bar
  140.  *     will first be placed.  Leave this NIL to begin at option 1.
  141.  *
  142.  *  <lRestscrn>  is a logical to designate whether or not the screen
  143.  *     coordinates occupied by the box and/or shadow should be restored
  144.  *     before FT_Ach2tb() returns.  The default is .T.
  145.  *
  146.  *  <nTimeout>  is the number of seconds after which FT_ACH2TB() will
  147.  *     timeout and return to the function/proced. which called it.  The
  148.  *     default is 0.
  149.  *
  150.  *  <nTimeoutVal> is an optional alternative numeric value FT_ACH2TB() will
  151.  *     RETURN when/if it times out.  The default is the current element
  152.  *     number.
  153.  *
  154.  *  <bUserfunc>  is a code block containing a function call to be
  155.  *     executed after each key press.  You need to write just two formal
  156.  *     parameters to allow the run-time passing of the key pressed and the
  157.  *     current element number, e.g.:
  158.  *               { |key,num| Myfunc( key,num [,other params.] ) }
  159.  *     Unlimited extra parameters may be passed.  Of course, make certain
  160.  *     to also write 'receptors' for them in 'Myfunc()' itself...as in the
  161.  *     above example.  The default is NO user function.
  162.  *
  163.  *  $RETURNS$
  164.  *     the number of the selected option, or 0 if [Esc] is pressed.
  165.  *
  166.  *  $DESCRIPTION$
  167.  *     FT_Ach2tb() is a greatly enhanced, fully featured, and now mouse-
  168.  *     supported replacement for Achoice(), based on a Tbrowse object. 
  169.  *     Each element of <aArray> (the array you pass to it) is itself an
  170.  *     array.  Each element can solely composed of "Option" (below), but
  171.  *     may be composed as follows to take full advantage of the function's
  172.  *     features:
  173.  *
  174.  *         Option   ,     Message      ,HotKeyPos,HotKeyColor,Selectable
  175.  *     { "Utilities","System Utilities", 3       ,"+gr/b"    ,.T. }
  176.  *
  177.  *     All elements except for the first, the option itself, are optional.
  178.  *     IF 'Message' is NIL, no message is displayed.  'HotKeyPos' is the
  179.  *     position within 'Option' of the hotkey.  In the example above, the
  180.  *     hotkey for 'Utilities' is the first 'i', i.e., at position 3.  The
  181.  *     default is 1.  'HotKeyColor' is the color to use for the hotkey
  182.  *     display.  The default is hiwhite  on the current background color.
  183.  *     'Selectable' is a logical indicating whether or not that option can
  184.  *     be selected.  The default is .T.
  185.  *
  186.  *     The A_CHOICE() UDC in FT_ACH2T.CH makes using FT_ACH2TB() a breeze.
  187.  *     The myriad of parameters can be written in